/*
 * Copyright (C) 2011 TopCoder Inc., All Rights Reserved.
 */
package gov.nasa.pds.services;

import gov.nasa.pds.entities.DataSet;
import gov.nasa.pds.entities.DataSetSearchCriteria;
import gov.nasa.pds.entities.HelpFile;
import gov.nasa.pds.entities.PagedResults;

import java.util.List;

/**
 * A comprehensive service to get data for the users.
 * 
 * Thread Safety: The implementations should be effectively thread-safe.
 */
public interface DataSetService {
    /**
     * Gets the help file with the given name.
     * 
     * @param name
     *            - the name of the help file
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data
     * @return - the HelpFile that provides the path to the help file
     */
    HelpFile getHelpFile(String name) throws DataSetProcessingException;

    /**
     * Gets the data set with the given ID.
     * 
     * @param dataSetId
     *            - the ID of the data set
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the data set
     */
    DataSet getDataSet(long dataSetId) throws DataSetProcessingException;

    /**
     * Gets the data sets that meet the given criteria.
     * 
     * @param criteria
     *            - the criteria to match
     * @param page
     *            - the 1-based page
     * @param pageSize
     *            - the size of the page
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the data set that matches the criteria
     */
    PagedResults<DataSet> searchDataSets(DataSetSearchCriteria criteria, int page, int pageSize)
            throws DataSetProcessingException;

    /**
     * Gets the data sets that meet the given query.
     * 
     * @param adHocQueryString
     *            - the query to match
     * @param page
     *            - the 1-based page
     * @param pageSize
     *            - the size of the page
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the data set that matches the criteria
     */
    PagedResults<DataSet> searchDataSets(String adHocQueryString, int page, int pageSize)
            throws DataSetProcessingException;

    /**
     * Gets the related names of the given entity with the key word. It would search for names of the objects.
     * 
     * @param keyword
     *            - the keyword to look for
     * @param clazz
     *            - the class of the object
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the list of all related terms
     */
    List<String> getRelatedNames(Class<?> clazz, String keyword) throws DataSetProcessingException;

    /**
     * Gets the data sets that meet the given query.
     * 
     * @param page
     *            - the 1-based page
     * @param pageSize
     *            - the size of the page
     * @param predefinedQueryName
     *            - the query to match
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the data set that matches the criteria
     */
    PagedResults<DataSet> searchDataSetsByPredefinedQuery(String predefinedQueryName, int page, int pageSize)
            throws DataSetProcessingException;

    /**
     * Gets all predefined queries.
     * 
     * @param Return
     *            - the list of all predefined queries
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     */
    List<String> getPredefinedQueries() throws DataSetProcessingException;

    /**
     * Gets all popular queries.
     * 
     * @throws DataSetProcessingException
     *             - if there is an error while getting the data.
     * @return - the list of all predefined queries
     */
    List<String> getPopularQueries() throws DataSetProcessingException;
}
